昨天我們已經成功將元件發布到 npm 了，但各位有沒有發現少了一個很重要的東西？

在上傳成功後，npm 其實有給了一段提示文字："This package does not have a README. Add a README to your package so that users know how to get started."

當使用者進入這個畫面想要下載時，他不知道這個元件是什麼，也不知道該如何開始使用！
所以我們必須替他加上一個重要的使用說明書，告訴使用者這個元件是什麼，該怎麼使用。

開始寫 Readme 吧！

我認為 readme 是一個看似簡單，但寫起來並不簡單的東西，要如何讓使用者透過 readme 就能快速知道如何開始，真的是很大的學問。
因為目前公司正在開發共用元件的關係，其實也接觸到了不少關於撰寫元件 readme 的知識，雖然不一定是對的，但大方向可以提供大家參考參考！

縷一縷整體架構

其實可以從之前的文章中發現，每一步的基礎概念都可以體現在 readme 中，包含之前所學的屬性、樣式、方法，再到安裝及使用，你其實都學過了！現在就差把它們組合在一起。

先一步一步拆解區塊架構：

• 介紹你的元件：初步介紹元件是什麼，主要的功能是什麼，可以用在什麼情境。
• 如何安裝元件：安裝元件需要有什麼樣的環境，應該要下什麼指令安裝。
• 如何使用元件：安裝完元件，應該怎麼使用才能看見元件。
• 元件的 DEMO 頁：（本次沒有實作，所以這段先忽略）。
• 元件的初步使用程式碼範例：提供使用者參考的基本範例。
• 元件的相關屬性說明。
• 元件的相關方法說明。
• 元件的相關樣式說明。
• 元件的 Change Log 區塊。
• 元件的憑證。

那麼接下來為了讓元件更通用更符合國際化需求，所以我們使用英文來撰寫 readme 吧 XD！

首先，你需要在專案的根目錄先建立 README.md 的檔案。

Introduction:

This is a form input web component that supports multiple types and content validation.
You can add your own validation settings and style types.

Install:

You can install un-custom-input with npm, or just get started quickly with CDN.

• npm

npm i un-custom-input

After the package is installed, then you can import the input web component into you code:

// import element in your JS file
import 'un-custom-input';

<!-- use element in HTML -->
<un-custom-input></un-custom-input>

• CDN

<script type="module" src="https://unpkg.com/un-custom-input/dist/custom-input.mjs"></script>

<!-- use element in HTML -->
<un-custom-input></un-custom-input>

Basic Usage:

• basic text input with defaultVlaue & min/max length

<un-custom-input
  name="basicInput"
  value="default value"
  max-length="5"
  min-length="2"
>
</un-custom-input>

• password input with required attribute

<un-custom-input
  name="password"
  placeholder="請輸入密碼"
  required
  type="password"
>
</un-custom-input>

• email input with pattern and pattern message

<un-custom-input
  name="email"
  placeholder="your@email.com"
  pattern="^[^\s@]+@[^\s@]+\.[^\s@]+$"
  pattern-message="invalid email pattern"
  required>
</un-custom-input>

Attribute

Methods

Properties

Events

Styling

Three parts that can be styled using the ::part() pseudo-element:

example:
In your style.css overwrite style.

custom-input::part(container) {
  display: flex;
  flex-direction: column;
  gap: 8px;
  background-color: #f0f0f0;
  padding: 10px;
  border-radius: 8px;
}

Change Log

[1.0.1] - 2025-10-02

• Update readme.

License:

MIT License.

以上，就一起一步一步的完成自訂元件的使用說明了！
但由於我們更新了 README, 所以我們需要重新發布新的版本。

• 先在 terminal 輸入 npm version patch 更新版本號，從 v1.0.0 變為 v1.0.1。
• 在 terminal 輸入 npm publish，重新發布。

那麼，這個元件也算是完整的發布成功囉～✧*｡٩(ˊᗜˋ*)و✧*｡